====================================================================
 DASHBOARD SUITE - GRANULAR FEATURES
====================================================================
 Written from a fresh read of the code on 2026-10-30, not from the
 older documents. Every count, threshold, timing, URL and rule below
 comes from the source file named beside it. This is the suite's only
 document. To start everything, double-click START (Mac).command or
 START (Windows).bat. PART 10 lists where the code disagrees with itself.

 PART 1  The suite at a glance
 PART 2  Stocks Watchlist            stocks_dashboard/
 PART 3  Truth Social Filter   truth_social_filter/
 PART 4  China Russia Middle East    china_russia_middleeast_dashboard/
 PART 5  Company Positive/Negative   company_positive_negative_5_day_news/
 PART 6  God's Eye                   gods_eye_dashboard.html + tools/
 PART 7  Launchers and portable runtime
 PART 8  Reading it all as text (summaries, SKILL.md, plugin.js)
 PART 9  Tests and developer scripts
 PART 10 Mismatches and unused code found while writing this
 PART 11 Running it: USB, Android and troubleshooting


====================================================================
 PART 1  THE SUITE AT A GLANCE
====================================================================

 Window                    Kind                    Address or file
 ------------------------  ----------------------  ---------------------------
 Stocks Watchlist          Flask server (Python)   http://127.0.0.1:8766
 Truth Social        stdlib server (Python)  http://127.0.0.1:8765
 China Russia Middle East  generated HTML file     ..._dashboard.html
 Company Pos/Neg 5 Day     Node server             http://127.0.0.1:8194
 God's Eye                 single HTML file        gods_eye_dashboard.html

 The company list
 companies.txt in the suite folder is the live list for the stocks watchlist and
 company news. Both check the folder every 3 s: drag the file out and both lists empty;
 drag a fresh companies*.txt in (the newest wins) and both use it. This copy ships with
 no list: both start empty until one is added. God's Eye HQ markers follow a list dropped
 on that page. watchlist.py and companies.mjs are empty lookup tables that can hold checked
 tickers and tuned news queries; tools/test_summaries.py fails if those two drift apart.
 China/Russia has no company list: it is news from 5 outlets.

 Feed filter (tools/feed_filter.py)
 While no companies*.txt is in the suite folder, news items, Truth Social posts, launches and
 satellites naming a company in tools/data/feed_filter.json (stored as hashes) are left out, and
 the ISS layer is hidden. Add a companies*.txt and they all come back within a few minutes.

 Rules that repeat across all of them
 - Nothing invented. A source that gave nothing shows as unavailable,
   cached or saved with a date; never a sample, zero or guess.
 - Every source has a last-real-copy fallback on disk, labelled as old.
 - Portable: no absolute paths, runs from an exFAT USB stick on Mac and
   Windows; God's Eye also runs on Android.
 - Read-only sticks are survived: every disk write is guarded.
 - Writes are atomic (temp file then rename) so a pulled stick or a kill
   cannot leave half a file.
 - Servers bind to 127.0.0.1 only.
 - Console output is ASCII-safe for Windows consoles.
 - Every window can be read as stamped plain text (PART 8).


====================================================================
 PART 2  STOCKS WATCHLIST
====================================================================

 2.1 THE LIST (watchlist.py, custom_list.py)
 - No companies ship with this copy. A name with no ticker is treated as private or
   unlisted (ticker=None).
 - CURRENCY map for listings not quoted in USD, empty here.
   Anything else defaults to USD on the list; a fallback listing reports
   its own currency.
 - Drop a .txt file on the page to replace the list:
   - Line forms: "Name", "Name (TICKER)", "Name, TICKER", "Name - TICKER",
     "- Name", "1. Name". Blank lines, # and // are ignored.
   - "(UK)", "(US)", "(NYSE)", "(OTC)" and similar are notes, not tickers.
   - Names on the built-in list keep their checked ticker (normalised
     exact match, no prefix guessing: "Acme" is not Acme Energy).
   - Others go through the private-company search below.
   - Saved as cache/custom_watchlist.json; watchlist.py is never edited.
   - Limit 2 MB. UTF-8 or UTF-16 (Windows Notepad "Unicode") accepted.
   - "Reset list" deletes the custom file and returns to companies.txt in the folder.
     A change to the file in the folder also replaces a list dropped on the page.
   - A dashed overlay appears while dragging a file over the window.

 2.2 PRICE DATA CHAIN (stock_fetch.py)
 One ticker walks these in order and stops at the first real series:
   1. yfinance      each Yahoo symbol; 5y, then 1y, 6mo, 3mo
   2. FT markets    each FT listing, 1,100 days; if its id fails it is
                    re-resolved through FT search and saved (ft_xids)
   3. Nasdaq        US listings, 1,100 days, stocks then etf asset class
   4. Yahoo direct  chart API, 5y; 30-minute circuit breaker after a refusal
   5. Stooq         CSV; same 30-minute circuit breaker
 - FALLBACKS (hand-checked chains with alternate listings) and SINGLE_SOURCE (weak
   tickers and why) ship empty.
 - Tickers found at runtime get a chain built by ensure_chain(), with FT
   candidates checked against exchange and company name.
 - Each result names its source, symbol, currency and last bar date.
 - Timeouts 12 s (8 s for the legacy sources). One requests session per
   thread. A bad row ("n/a") is skipped, not fatal. Needs 5+ bars.
 - Pence stay distinct from pounds: GBX/GBp to GBp, also ZAc and ILA.

 2.3 CACHING AND PACING
 - Good quote fresh 5 min; failure remembered 2 min. Memory only.
 - Warm-up on start: 10 tickers per section, 1.5 s between sections, one
   at a time, because Yahoo rate-limits bursts.
 - /api/quote allows 2 concurrent fetches.
 - The page fetches sequentially too, re-rendering every 10 tickers, with
   a progress bar and "Loading n / total".
 - Page reloads everything every 5 min; a pass still running is not doubled.

 2.4 INDICATORS
 RSI           Wilder 14-period on daily closes. 100 when no losses, 50
               on a flat series, none under 15 closes.
 1-year high   Highest close in the last 260 bars;
               (1 - price / high) x 100. Marked * with a tooltip when
               under 300 days of history (it is a shorter-window high).
 Vol spike     Mean absolute daily move over the last 14 bars above 1.5x
               the window mean; needs 20 closes. Price moves, not volume.
 HH & HL       Local peaks and troughs (higher or lower than both
               neighbours); confirmed when the last two highs AND last
               two lows are rising. Separately on daily (20 bars), weekly
               (12 bars) and monthly (24 bars). Daily and weekly come from
               260 trading days; monthly from up to 800. Shown only on
               stocks already oversold or a dip.
 Head and      Weekly chart, stock_fetch._calc_head_shoulders, returned by
 shoulders     /api/quote as "hs". Covers every listed stock (a top forms
               near the highs, not on dips).
   Series      Weekly closes (last close of each ISO week) from up to 800
               daily bars, about 3 years, as log prices. Needs 20 weeks.
   Swings      Zigzag at 8, 12, 18 and 25% swing sizes. A swing point
               counts only once price has moved that far away from it.
   Shape       Five swing points in a row: shoulder, trough, head, trough,
               shoulder. All of these must hold:
               - head ~8%+ beyond the neckline
               - head ~3%+ beyond both shoulders in price
               - each shoulder 30-85% of the head's height
               - shoulders within 35% of the head's height of each other
               - neckline troughs within ~15%
               - 8-104 weeks shoulder to shoulder
               - neither side over 2.5x the other in weeks
               - price came from below the neckline first (within 52 weeks)
   Types       top (bearish) and inverse (bullish). Inverse is the same
               test on the negated log series. If several match, the one
               with the newest right shoulder wins.
   Status      forming: neckline not closed through, right shoulder within
               13 weeks. confirmed: a weekly close through the neckline
               within 10 weeks and still through it.
   Dropped     Price retakes the right shoulder or neckline, the measured
               target (neckline minus head height) is reached, or it goes
               stale.
   Caveat      Closes only, since no highs or lows are fetched. The current
               week's bar is its latest close, so status can change before
               the week ends.

 2.5 THE PAGE (templates/dashboard.html)
 Headline cards, five with a colour stripe:
   Oversold alerts     count with RSI below the threshold
   Dip alerts          count at or past the dip threshold
   Higher highs/lows   daily, weekly, monthly counts, alerted stocks only
   Head & shoulders    top and inverse counts, plus how many confirmed
   Stocks watched      total including private
 Alert controls:
   Checkboxes: oversold, 1yr dip, volatility spike (feed the "n alerts"
   count). Sliders: RSI 20-40 (default 30), dip 30-90% (default 33%).
   Changes re-render at once with no refetch.
 All stocks table:
   Columns: plain grey dot, company + ticker, RSI, vs 1yr high, price, signals.
   Filter tabs: All, Oversold, Dip, HH&HL daily, weekly, monthly,
   H&S top, Inverse H&S, Vol spike.
   Search by name or ticker; / focuses it, Esc clears it.
   Legend explains every colour. Sticky header. Row tooltip shows symbol,
   source and last bar date.
 Colours:
   Oversold red, dip orange, HH&HL daily green, weekly purple, monthly
   pink, vol spike blue, H&S top yellow, inverse H&S cyan.
   H&S badge: solid = neckline broken, tinted = forming. Hovering shows
   shoulders, head, neckline and measured target with dates.
 Other row tags: private, non-USD currency, non-yfinance source.
 Prices: formatted in the listing's currency (symbol table for USD, EUR,
 GBP, pence, NOK, DKK, SEK, AUD, CAD, JPY, KRW, CHF; other codes written out).
 Refresh button: asks the server to refetch (/api/refresh), then re-reads
 at once and after 20, 60 and 120 s.
 Mobile: cards go 5, then 2 columns at 1080 px (the fifth spans the row),
 1 column at 660 px; signals wrap under the row.

 2.6 SIDE CARDS
 Fear & Greed (app.py)
   CNN graphdata endpoint with cnn.com Origin/Referer (it answers 418
   otherwise). Fresh 15 min, retry 2 min, last value kept in
   cache/feargreed.json. Needle gauge and colour bands at 25, 40, 60.
 World Economic Forum (wef_events.py)
   weforum.org/events via curl_cffi (Akamai answers 403 to plain clients).
   Parsers: Apollo state, Angular ng-state, JSON-LD, regex.
   Next Davos: the listing, else the WEF meeting page, else davos.ch, and
   only when explicit dates are published; a note names the source or says
   dates are unpublished. Dates are never guessed.
   Fresh 6 h (1 h after failure), plus a 30 min app-level cache; 28 s budget.
   Saved copy is re-filtered against today, so ended events drop off
   offline. Page shows countdown badges and "in progress".
 Topic news (app.py), Google News RSS, en-GB, last 365 days:
   Psychedelics, DMT and cannabis legalisation, US and UK: 9 queries, must
   match a drug term plus US policy and US place terms, or a UK term.
   CGT rates and stocks ISA policy: 8 queries, must match CGT or stocks ISA
   plus a change term; cash ISAs excluded.
   Word-boundary regexes stop "dea" hitting "deal", "bud" hitting "budget".
   Dedupe on the first 60 normalised characters. Max 30 per panel, newest
   first. 5 parallel searches. Fresh 30 min, retry 5 min.
   Last real batch in cache/news_drugs.json and news_tax.json. Status line
   says live, cached with date, unreachable or no matches.
 Historical crashes table: 18 crashes from 1907 to 2022, hard-coded
   (period, peak drop, duration, index).
 Interest rates (central_banks.py), Fed and Bank of England:
   Rate: FRED DFEDTARU/DFEDTARL; BoE IADB IUDBEDR.
   Calendar: federalreserve.gov fomccalendars; BoE upcoming-mpc-dates.
   Decision: Fed press RSS + statement page; BoE summary-and-minutes page.
   Also Fed chair (fomc.htm) and 5-year peak rate.
   Shows rate, decision, vote, dissents, last and next meeting, peak,
   statement note, source link.
   States: live, cached (cache/central_banks.json), built-in (real values
   captured 2026-09-16 in the code).
   Decision day: re-checks every 5 min until parsed; stays quick for 48 h
   after a missed decision. Otherwise 30 min. 38 s budget.
   Announced but not yet parsed: "Awaiting details" with a warning box,
   and the old decision labelled as old. FRED rows over 10 days and BoE
   rows over 45 days old are not called live.
   curl_cffi fallback for sites rejecting plain requests.
   /api/rates has open CORS for God's Eye; 503 until both banks exist.
 Liquidity (liquidity.py), re-checked hourly, retry 5 min:
   US M2           FRED M2SL, monthly, $T; 1 mo and YoY
   Fed Net Liq.    WALCL - WTREGEN - RRPONTSYD, weekly; 1 wk, 4 wk, YoY;
                   components listed
   China M2        Eastmoney, monthly, CNY T; 1 mo and official YoY; M1 line
   PBoC Net Liq.   Total assets - government deposits, via Sina, monthly;
                   1 mo, 3 mo, YoY
   Sparklines (36 months or 104 weeks), each gauge cached separately in
   cache/liquidity.json and labelled when cached.
 American Power Index (kpow.py), bottom of the page, the page polls every 30 s:
   Kalshi's KPOW, +50 D to +50 R. Value, 24h change, 12-month chart (hourly
   points plus the latest reading, red = Republican lean, blue = Democrat lean,
   hover for any hour's value). History re-read every 30 min, kept in
   cache/kpow.json and labelled when cached; flagged if Kalshi's own reading
   is over 30 min old.

 2.7 PRIVATE COMPANIES (check_private.py)
 At every start each ticker=None name is searched on Yahoo (FT if Yahoo
 refuses). A match must be an equity symbol with no exchange suffix (FT search: US
 listings), pass a name check, and return a real price through the chain. Funds named after a
 private company are rejected. A match is promoted for the session and
 printed to the console; watchlist.py is not rewritten.

 2.8 ENDPOINTS (app.py)
 /                  the page
 /api/stocklist     GET list; POST a dropped file; DELETE to reset
 /api/listsource    which list is in use
 /api/quote?ticker= one quote (ticker checked against a pattern)
 /api/debug         per-source attempt log (?tickers=, ?limit=)
 /api/feargreed /api/volx /api/news /api/rates /api/wef /api/liquidity /api/kpow
 /api/summary       stamped text, ?format=json
 /api/refresh       refetch everything in the background
 /api/volx          VIX candles, 1 year: Yahoo, then CBOE CSV, then FRED
                    VIXCLS. Used by the text summary only.
 All /api responses and the page are no-store.

 2.9 STARTUP BEHAVIOUR
 - Port 8766; STOCKS_DASHBOARD_PORT overrides. If taken by this dashboard
   it just opens the browser; if taken by something else it tries the next
   29 ports (skipping 8765) and warns God's Eye's rates layer will be off.
 - DASHBOARD_NO_BROWSER=1 skips opening a tab.
 - Optional modules (central_banks, wef_events, liquidity) failing to
   import only blanks their card with the error.
 - Background threads never delay the server. A summary file is written
   after 90 s, then every 5 min.


====================================================================
 PART 3  TRUTH SOCIAL FILTER
====================================================================

 3.1 FEED (rss_server.py, Python standard library only)
 - Sources in order: truthsocial.com/@realDonaldTrump.rss (often 403 to
   non-browsers), then the trumpstruth.org mirror.
 - Refetched every 2 min. 15 s socket timeout, 25 s total, 32 MB cap.
 - Last real feed kept in cache/last_feed.xml and .json, loaded at start.
 - Over 15 min old, or from disk, it reports as a saved copy.
 - HTTPS: system trust store first, certifi if verification fails (a fresh
   python.org Mac install has no CA bundle).

 3.2 CLASSIFICATION (page JS, ported to filter_rules.py line for line)
 - Keyword test: no letter or digit before the key; keys of 3 characters or
   fewer must also end at a boundary ("ai" not in "said", "dow" not "down");
   longer keys are stems ("negotiat").
 - 8 tags: economy, foreign policy, strategic theme, thematic exposure,
   long-duration growth, future-facing, high-conviction, macro trend.
   A post with none is tagged economy.
 - Sentiment: count of 34 bullish vs 17 bearish words; more wins, tie neutral.
 - Only bullish posts in the last 21 days are shown, newest first.
 - Impact: high keys (executive order, signed, tariff, reserve, nato, rate
   cut, deal, billion, trillion); else med keys (negotiat, discuss, working
   on, meeting, call with, progress); else low. 3+ assets lifts low to med.
 - Asset exposure: 11 keyword rules map to up to 6 tickers per post, with
   up to 2 highlighted. Examples: bitcoin to BTC IBIT; tariff to DXY SPY XLI.
   All of them are funds, indices and currencies, not companies.
 - Undated posts are dropped, never given a time. Posts of 10 characters or
   fewer are dropped.

 3.3 THE PAGE
 - Stat tiles: bullish posts, high impact, days covered, latest post.
 - Search box and ticker filter; both update the tiles.
 - Post card: bullish badge, tags, impact, date, text to 400 characters,
   exposure pills, link to the post.
 - Status line: Live, Saved copy with fetch time, or unavailable; names the
   source.
 - Falls back to its own browser copy (localStorage) if the server is gone.
 - Refresh button forces a fetch (20 s timeout); re-reads every 5 min.
 - Feed text is untrusted: escaped, and parsed with DOMParser so nothing in
   a post can run.

 3.4 SERVER ENDPOINTS
 /  /rss  /status  /summary (?limit=1-200, ?format=json)  /refresh
 /china/regen  /china/status  /proxy/<key>  /proxy/ships
 /refresh and /china/regen accept only the suite's own pages or no browser
 Origin, so another website cannot trigger them. RSS_SERVER_PORT overrides
 port 8765. Threaded, so one slow upstream cannot freeze other requests.

 3.5 THE RELAY FOR GOD'S EYE (rss_server.py, godseye_feeds.py)
 A page opened from disk cannot read feeds without CORS headers, so named
 upstreams only are relayed, never an arbitrary URL.
 Key       Upstream                            Fresh for   Stale kept
 mil       api.adsb.lol/v2/mil                 20 s        1 h
 mil_fi    opendata.adsb.fi/api/v2/mil         20 s        1 h
 buoys     NOAA NDBC latest_obs.txt            10 min      1 h
 ladd      adsb.lol LADD (or adsb.fi sweep)    60 s        1 h
 pia       adsb.lol PIA (or adsb.fi sweep)     60 s        1 h
 bizjets   adsb.lol by jet type (or sweep)     5 min       1 h
 starlink  CelesTrak group=starlink            2 h         3 days
 - One fetch per key at a time; 15 s backoff after a failure; 16 MB cap;
   30 s whole-download deadline. X-Fetched-At and X-Relay-Stale report age.
 - Business jets: 46 ICAO type designators, one query a second, 75 s budget.
 - adsb.fi sweep: 250 nm circles over busy airspace, one per 1.6 s, 30 s
   pause between rounds; used for 10 min when adsb.lol says 429.
 - Ships: optional worldwide AIS from aisstream.io with a free key
   (AISSTREAM_API_KEY or aisstream_key.txt). A hand-written websocket client
   with reconnect backoff 5-300 s; ships forgotten after 30 min without a
   position. Without a key the page uses Digitraffic (Baltic).

 3.6 CHINA REGENERATION
 /china/regen runs the China generator once at a time, stopped after
 10 min; a failure keeps the old page.


====================================================================
 PART 4  CHINA RUSSIA MIDDLE EAST FILTER
====================================================================

 4.1 GENERATOR (app.py; writes files, no server)
 - Window: last 120 hours (5 days).
 - Outlets and feeds:
     Al Jazeera        all.xml
     The Moscow Times  rss/news, rss/all
     RT                rss/, rss/news/
     SCMP              rss/91, rss/4, rss/5
     CGTN              section/world.xml, section/china.xml
 - Every feed of an outlet is merged (one feed often only reaches 1-2 days).
 - RSS failed entirely: homepage scrape, links with 20+ character titles,
   date from a nearby <time>, up to 60; no date shows as "Date unknown" last.
 - Dedupe by link and normalised title. Summaries cleaned, cut to 280 chars.
 - Sports removed with whole-word, unambiguous terms only (football, nfl,
   wimbledon, boxing, ...). The code records why words like "match" and
   "coach" were dropped: they removed real news.
 - Nothing fetched: exits 1 and keeps the old page and files.

 4.2 THE PAGE
 - Single file that opens from disk. Sticky header and controls.
 - Stats strip: total and per outlet.
 - Source filter buttons, each in its outlet's colour; search on headline and
   summary; / focuses it, Esc clears it.
 - Grouped by UTC day. Card colour-coded by outlet, outlet badge on hover.
 - Click to expand the summary and full time; arrow, or Ctrl/Cmd-click, opens
   the article. Keyboard: Enter or Space expands.
 - "12m ago" is worked out in the browser, so an old saved page never claims
   fresh news. Updated every minute.
 - Save to text doc: shown headlines only, one per line, filter applied.
 - Read aloud: browser speech, offline; play/pause, back, skip, voice menu,
   1x/2x, remembered per browser; highlights and scrolls to the story; reads
   what the filter shows. Controls hidden if the browser has no speech.
 - Auto-reload every 10 min, and on return to a tab hidden that long; keeps
   filter, search and scroll; never reloads while reading aloud.
 - Refresh button: asks the relay on 8765 to regenerate, polls every 2 s up
   to 4 min, reloads. No relay: reloads the saved page and says so.

 4.3 FILES WRITTEN
 china_russia_middleeast_dashboard.html, _news.json (every article),
 _summary.txt (12 headlines a day, rest counted). Only after a successful
 fetch, atomically. Retries 5 times on a Windows file lock.


====================================================================
 PART 5  COMPANY POSITIVE / NEGATIVE 5 DAY NEWS
====================================================================

 5.1 THE SWEEP (server.mjs, Node, no dependencies)
 - 209 rows in companies.mjs: name, theme, news query, title-match regex.
 - Google News RSS per company with "when:5d", en-US. 15 s timeout, one retry
   on 429 or 5xx, 4 at a time, 250 ms between.
 - Full re-sweep every 30 min, and at start. Saved to cache.json, keyed by
   name so a list edit cannot show one company's news under another.
 - A failed fetch keeps the last good bullets still inside the window.
 - Bullets older than 5 days are never served, even from an old cache.

 5.2 SCORING
 - Title must match the company regex (whole words: "Den" not "Denim").
 - The company's own name is removed first ("Acme Growth", "Growth Solutions"
   must not score themselves).
 - Word lists: positive (surge, beat, contract, upgrade, ...) and negative
   (fall, lawsuit, downgrade, recall, ...). +1 or -1 per hit.
 - Whole words with plain inflections only, so "ban" does not hit "Bank",
   "miss" not "missile", "win" not "window". True stems stay open.
 - Negation flips a hit: not, no, never, without, avoids, no longer, fails to,
   despite, ends, lifts, within two words before.
 - Score 0 is left out. Above 0 positive, below 0 negative.
 - Newest first, 6 slots each side; totals kept uncapped for net counts.
 - Dedupe on the first 50 normalised characters.
 - Display titles shortened to 90 characters, boilerplate removed; scoring
   always uses the full headline.

 5.3 THE PAGE (index.html)
 - One card per company, positive and negative columns, green and red
   markers; source and age on hover.
 - "No clearly positive or negative headlines", "fetching", "fetch failed".
 - Filter box, Refresh now, status ("updating n/total", "updated 12m ago").
 - Polls every 15 s, re-rendering only when data changed so scroll holds.
 - Save to text doc: whole list to a dated .txt in this folder; read-only
   stick falls back to Desktop, then temp.
 - Read aloud: company name then headlines as short pieces; click a company or
   beside a headline to start there; back, skip, voice menu (English first),
   1x/2x, remembered. Highlights without scrolling, so you can browse.
 - Drop a .txt list to replace it (custom_list.json); known names keep their
   tuned query; "Reset list" undoes it.
 - Works from file:// too, talking to the server on 8194.

 5.4 ENDPOINTS
 /api/data  /api/summary (?limit=1-6, ?companies=1-300, ?format=json)
 /api/save (POST)  /api/list (POST, DELETE)  /api/refresh
 Save, list and refresh reject other websites' origins.
 Selftest: node server.mjs --summary-selftest.


====================================================================
 PART 6  GOD'S EYE
====================================================================
 Depth of this section: the tools, data blocks, feed tables and layer list
 were read directly. The roughly 4,000-line app script was read through its
 comments, function list, URLs and constants, not line by line, so small
 rendering details may be missing here.

 6.1 THE FILE
 gods_eye_dashboard.html, about 23 MB, one self-contained page. Opens from
 disk with no server or network on Mac, Windows and Android. three.js r128
 and satellite.js 5.0.0 are inlined; every dataset is a <script id="..."> block.

 6.2 THE GLOBE
 - Earth sphere, filled countries (precomputed triangles, one merged mesh),
   graticule, stars, relief normal map lit from the real sub-solar point.
 - 3D terrain: NOAA ETOPO1 on a 1801 x 901 grid (0.2 degree, highest sample in
   each cell, 10 m steps). Menu x1 true scale, x3, x10 default, x20, off;
   ?terrain=N overrides; choice remembered. Mesh every 0.2 degrees on desktop,
   0.4 on phones. Hypsometric colours, snow only above 5,200 m, baked hillshade.
   Every surface layer is lifted by the ground under it, so markers sit on
   mountains.
 - Lines are resampled along the great circle (max 1.5 degrees a step) so they
   do not dip through the sphere.
 - Fixed layer stack, so layers never clip into each other; only the Earth and
   land hide anything.
 - Day/night terminator and light position from pure astronomy, no API.
 - Controls: drag with inertia, the spot under the pointer stays under it;
   wheel or slider zoom, steps shrinking near the ground; a short lockout stops
   zoom and drag triggering each other. Touch: one finger rotates, pinch zooms,
   two-finger drag rotates, tap shows details.
 - The camera always looks straight at the centre of the Earth, at every zoom.
 - Idle spin after 45 s, one turn in about 4 min.
 - Small FPS counter in the bottom right corner, updated every second.
 - Clock in Europe/London time (handles BST and GMT).
 - Frame-rate governor: under 30 fps for 3 s drops resolution, over 55 fps for
   10 s restores it, 20 s hold. Chip cycles auto, HD, MED, LOW; remembered.
 - Loading screen forced away after 6 s; errors shown rather than stuck.

 6.3 LAYERS (64 switches, with all/none buttons and colour swatches)
 Every layer has its own colour; layers that are lines or use several colours show
 that in their swatch. No dot is larger than a small fixed size (radius 0.18 on a globe
 of radius 100; about 0.4 for boxy markers), and dense layers are 1-1.5 pixel points.
 Live or computed
   ISS, space objects with tracking, Starlink, military flights,
   private jets, private flights, launches (next 30 days), NOAA buoys, ships (6 types),
   temperature heat map (off by default), CCTV, stock exchanges open/shut, central banks,
   day/night line.
 Reference geography
   Equator, poles, tectonic plates, capitals (199), rivers, ports, submarine cables
   (TeleGeography, 733), cable landing points (1928),
   shipping routes (11, illustrative), chokepoints (13), China/Russia borders (black, one sharp line like all highlighted borders),
   highlighted borders (neon green: US, Greenland, Cuba, Argentina, Japan, South Africa,
   Georgia, Poland, South Korea, Australia, Germany, Thailand, Cambodia; black: Israel), black borders
   (Georgia, Morocco, Antarctica, England, France, Italy), UK and world rail (Natural Earth), rail
   termini (approximate), canals, airfields (OurAirports), photo sites, company HQs
   (none until a list is dropped on the page).
 Site layers: markers are looked up or hand-researched; points come from Wikidata,
 OpenStreetMap and OurAirports. 'Two sources' counts points confirmed by a second source.
   Layer                       Markers   Points  Two sources  Colour
   Military bases                  324     2975          497  brick red
   Military airfields                6     1745          525  rose
   Submarine ports                  29       20            2  mint
   Military training areas           0     1852           45  brown
   Special forces bases             62        0            -  dark orange
   Special forces training          18        0            -  olive
   Intelligence sites               59       85            0  lime
   Nuclear sites                   186      276          110  yellow / green
   CIA black sites (reported)       15        0            -  purple
   Aerospace sites                  17      172            0  lilac
   NASA sites                       20        0            -  blue
   Spaceports                        9       56           10  peach (41 more built in)
   Central banks                    31        0            -  gold (19 more built in)
   Ports                             0     4865          640  teal (1,082 more built in)
   Fishing ports                    43      351           13  light green
   Fishing villages                159        0            -  sea green
   Reservoirs                        0    64357         8175  deep blue (off by default)
   Prisons                         154     6771         1858  taupe
   Also: Antarctic stations (57), shipyards (78), aircraft carriers (28, dated reported
   positions), canals (34), private-jet airports (113), exchanges (71+31), EU and UN sites (62).
 Aerospace is a category of places, like shipyards. Its Wikidata rows and the spaceport
 rows are frozen and not refreshed (FROZEN_LAYERS in tools/gods_eye_wikidata.py).
 862 sites are marked verified against a linked source, 112 are marked unconfirmed with the
 reason. Data as of 2026-10-30; Wikidata built 2026-10-30.

 Coverage by country (includes the built-in lists; UK = England, Scotland, Wales and N. Ireland).
 Category              US    GL    CU    AR    JP    ZA    GE    PL    KR    AU    IL    CN    RU    TH    MA    KH    UK    DE    FR    IT
 Intelligence          22     0     6     2     7     1     1     6     2    11     5     8    15     2     4     0    11    24     7     6
 Military bases       593    12    14    69   199    57    41    68    72   104    87   465   182    66    31    48   408   328   195   220
 Military airfields   540     8     9    25    55    18     9    37    73    74    11   185   283    22    15     3   211    73    58    42
 CIA black sites        0     0     1     0     0     0     0     2     0     0     0     0     0     1     1     0     0     0     0     0
 Nuclear              118     3     2     9    54     5     2     4    12     5     3    54    49     2     2     0    39    34    38    11
 Aerospace             75     0     0     4     6     1     1     5     3     3     2    12    26     1     1     0    19    12    13     5
 NASA                  17     0     0     0     0     0     0     0     0     1     0     0     0     0     0     0     0     0     0     0
 Central banks         14     0     1     1     2     2     1     1     1     1     1     2     1     1     1     1     2     3     1     1
 Ports                693    23    45   137   474    16     8   327    47   123    24   319   326    34    28     5   370   894   782   485
 Reservoirs         32181     0   188   154  1712   855    41   615  4208  2786    94 14451  1254   948    79   103  1594  1420   995   679
 Submarine ports       13     0     0     1     1     1     0     1     1     3     1     4     8     0     0     0     2     3     8     2
 Cable landing pts    174     5     4     3    68     8     1     1    10    28     8    24    28     7     6     1   126     9    29    55
 Spaceports            24     0     0     4     8     1     0     0     2    12     2     8    11     0     0     0     9     1     3     3
 Fishing ports         15     7     4     6   235     6     3    29    23     7     4     9     9     8    11     5    40    22    51    11
 SF bases              10     1     0     2     2     3     1     5     1     2     3     1     9     2     0     0     3     4     5     4
 SF training            5     0     0     0     1     1     2     1     0     1     0     0     1     0     0     0     2     1     2     1
 Prisons             2706     5    72   194   157   122    14   257    46   177    40   799   739    88    37    20   435   436   318   242

 A zero means nothing was found in public sources, or the thing does not exist there: no
 NASA centres abroad beyond Australia, no CIA black sites reported in most countries, no spaceport
 in Georgia or Cuba. Special forces training and
 submarine ports are thin because most are secret. Cuba has no public special forces bases.
 Filters: police posts (gendarmerie, carabinieri), barracks with only one source, marinas, wartime
 camps and past detention sites are removed, because Wikidata files them as bases, ports or prisons.
 Antarctica is covered by the Antarctic stations layer; the treaty bans military bases there.

 Rail links between highlighted countries, and from England (20 corridors)
 Only track that physically exists is drawn. Left out: Abkhazia-Zugdidi (bridge destroyed,
 track removed) and Seoul-Kaesong (blown up by North Korea, 2024). The line is drawn straight
 between listed stations; it does not follow every curve of the real track.
   running: Trans-Manchurian, Grodekovo-Suifenhe, Trans-Mongolian, China-Laos-Thailand,
     Adler-Sukhumi, London-Paris, London-Brussels-Cologne-Frankfurt and on to Berlin-Warsaw
     (with changes; no through train), Berlin-Warsaw, Paris-Turin-Milan
   freight: Tongjiang bridge, Kaliningrad-Braniewo, Makhalino-Hunchun (round the clock since
     2022), Russia-Azerbaijan-Georgia (Russia-Azerbaijan confirmed, 7.8 Mt Jan-Aug 2026; through
     cargo on to Georgia not confirmed), China-Europe land bridge (Poland closed the Belarus
     border in Sept 2025; volumes reported growing in 2026; check before relying on it)
   suspended: Bangkok-Poipet-Phnom Penh (no through passenger trains; border freight since 2023),
     London-Warsaw-Brest-Moscow (Poland-Belarus passenger trains stopped March 2020)
   track exists, service not checked: Paris-Strasbourg-Frankfurt, Munich-Brenner-Verona.
   track exists, service not confirmed: Yiwu-Barking (China-England). Opened 2017; no 2025-26
     report of it running was found, and Barking's cross-Channel freight is being re-established.
   England has no land route to Morocco, Japan, Australia, Cuba, Greenland, South Korea,
   Argentina, South Africa or Israel, and none confirmed in use to Georgia, Thailand or Cambodia.

 Up to date, and what "live" means here
   Live: the feeds in 6.4, polled from the source. Bases, prisons, reservoirs and the rest have
   no public live feed. Instead START rebuilds and cross-checks them daily while it runs, and
   the feeds panel shows their age. If the suite is off they do not update.
   Cross-check as of 2026-10-31: all 20 countries against OpenStreetMap (through QLever) and
   OurAirports. 15 queries, a few minutes for the whole planet.
   Closed sites are removed only when the same kind of site, within 1 km, shares a distinctive
   name word with a closed record; museums and memorials are removed by name. The latest run's
   list is in tools/data/gods_eye_crosscheck_log.json. Three known-active airfields are exempt. A
   marker a second source calls closed is kept and marked disputed (Kampong Chhnang, Cambodia).
   Most rows still have one source: a site can be real with no second record, and a closed site
   with no closure recorded anywhere can remain.
   QLever's OpenStreetMap copy can lag the live map by days or weeks.
   Unconfirmed: Yiwu-London has no report of running in 2025-26, so it stays labelled that way.
   886 sites are marked verified against a linked source, 90 unconfirmed with the reason.

 6.4 LIVE FEEDS
 Feed            Polls every   Source order
 ISS             5 s           wheretheiss.at, else computed from newest TLE
 Military        30 s          relay, adsb.lol, adsb.fi, snapshot
 Private flights 90 s          relay LADD + PIA, snapshot; jets already shown removed
 Ships           2 min         Digitraffic + aisstream (relay, with key), snapshot
 Private jets    5 min         relay, snapshot; under half of types = not "live"
 Buoys           10 min        relay, snapshot; coloured by water temperature
 Fed/BoE rates   10 min        stocks server :8766
 Cameras list    30 min        TfL JamCam, 890 embedded; images fetched fresh
 Temperature     30 min        Open-Meteo, 120 grid points, only while layer is on
 Launches        30 min        Launch Library 2, ~15 calls/h, kept in browser
 Satellites      2 h           CelesTrak + SATCAT owners, snapshot, 2 built-in TLEs
 Starlink        2 h 30 s      relay, CelesTrak direct, browser copy, snapshot

 - Each feed owns one timer. Failure backs off 2x, 4x with 10% jitter, capped at
   15 min. Non-fresh feeds retry when the network returns or the page is shown.
 - "live" only while younger than that feed's limit (military 90 s, satellites
   3 h, launches 30 min), then "stale, last live N min ago"; "cached" shows the
   snapshot's age. Never claims live for data that stopped.
 - Feeds chip opens a panel of every feed; refresh chip refetches everything.
 - Starlink: about 10,600 sets, about 300 SGP4 runs a frame, refreshed about twice a
   second. CelesTrak refuses re-downloads within 2 h, hence the kept copy.
 - Military aircraft show a short line of where they will be in about 10 min.

 6.5 INTERACTION
 - Search: / or Ctrl/Cmd+K, every layer's names; picking flies there and opens details.
 - Click satellite: follows it, ground track, footprint, details panel.
 - Hover labels; click panels with outbound links (globe.adsb.lol, MarineTraffic,
   NOAA station page, Wikipedia, OurAirports). Esc closes a panel.
 - Far-side markers cannot be picked. Dense satellite shells are tried last.
 - Drop a .txt list: HQ layer switches to it. Known companies keep their data; new
   names looked up on Wikidata. Kept in the browser; reset restores built-in.
 - Top chips: feeds, refresh, fps, then a count for each main layer.

 6.6 SNAPSHOT TOOL (tools/gods_eye_embed.py, standard library)
 - --snapshots-only (what launchers run): military, launches, buoys, satellites,
   cameras, jets, private flights, ships, Starlink (only if saved set 2 h+ old).
 - Without it, also three.js, satellite.js, cables, landing points, borders.
 - --max-age H skips if newest snapshot is younger; --summary-only rewrites text
   from the page, no network; DIR argument reads files already downloaded.
 - Each block independent: a failed or implausible fetch keeps the old one. Floors:
   10 aircraft, 50 buoys, 2 TLEs, 100 cameras.
 - "captured" is the upstream's Date header when sent, so a wrong clock cannot mislabel.
 - Page rewritten atomically only if changed and validated; refuses if something else
   is writing it. 100 s total deadline. Exit 0 for network problems.
 - Writes gods_eye_summary.txt and .json.

 6.7 STATIC LAYER TOOL (tools/gods_eye_static.py, run by hand)
 Subsets: terrain ports airfields borders curated rail rivers. Sources: NOAA ERDDAP,
 Natural Earth 10m/50m, OurAirports, the curated JSON. Ports re-filed by point-in-
 polygon, plus 7 hand-added (Busan, Incheon, Gwangyang, Pyeongtaek-Dangjin, Mokpo,
 Nuuk, Sisimiut). Failed block keeps the previous one.

 6.8 WIKIDATA TOOL (tools/gods_eye_wikidata.py, run by hand, about 15 min; "titles" for the short lists)
 Queries Wikidata class by class for each of the 20 countries. Drops items with a closure or
 end date, prison museums, and any pin outside its country's Natural Earth outline (43+
 dropped at build, plus a German "Campbell Barracks" that a title wrongly matched). A failed
 class keeps its previous rows. Coordinates always come from Wikidata, never typed in.
 Wikidata text is CC0. Per-country counts: tools/data/gods_eye_wikidata_coverage.json.

 6.9 CROSS-CHECK TOOL (tools/gods_eye_crosscheck.py)
 Compares Wikidata rows with OpenStreetMap (whole-planet queries to qlever.dev) and OurAirports.
 Within 2 km and the same kind: confirmed by two sources. Named sites Wikidata lacks are added.
 Countries are assigned by a strict point-in-outline test, so neighbours' sites do not leak in.
 A failed query keeps previous rows. Runs after the Wikidata build in the daily refresh.

 6.10 ANDROID
 Open the file in Chrome or Firefox. No launcher, so relay feeds show dated snapshots
 and Fed/BoE rates are absent; direct feeds stay live. Termux can run rss_server.py.


====================================================================
 PART 7  LAUNCHERS AND PORTABLE RUNTIME
====================================================================

 7.1 START (Mac).command and START (Windows).bat
 - Launch everything; safe to run again. Bash 3.2 compatible on Mac; works as
   "bash file" because exFAT drops the executable bit.
 - Order:
   1. Unpack or find the runtime (below).
   2. Refresh God's Eye snapshots in the background if over 3 h old.
   3. Stop old copies of OUR servers only (matched by app.py, rss_server.py,
      server.mjs, refresh_loop.py). Anything else on the port is reported and
      left alone. Port 5000 is never touched (macOS AirPlay).
   4. Check packages; pip install any missing.
   5. Regenerate the China page.
   6. Start loops: China every 15 min, God's Eye every 60 min, site layers daily
      (and once at start if over 24 h old).
   7. Start the three servers; wait up to 20 s for each.
   8. Open the pages.
 - God's Eye and the saved China page open even if Python or packages are
   missing, so the stick is never useless. No Node: the other four still run.
 - Logs: dashboard_suite_*.log in the temp folder, never on the stick.
 - Closing the Mac window stops everything (trap on exit).
 - DASHBOARD_HEADLESS=1 (1, true, yes, on): starts servers, opens nothing,
   returns at once, prints where everything is; exit 2 if a server failed.

 7.2 STOP scripts
 Stop only the suite's servers on 8766, 8765, 8194 and its refresh loops.
 Anything else on those ports is left alone. Safe to run twice.

 7.3 Individual launchers
 Each dashboard has its own .command and .bat using the same runtime rules.

 7.4 Refresh loop (tools/refresh_loop.py)
 Runs a command every N minutes, first run after the first wait. A hung run is
 stopped after the interval or 15 min, whichever is longer. A failure is logged
 and old files stay.

 7.5 Built-in runtime (runtime/)
 - Python 3.13 with every package, plus Node 22, in mac-arm64.tar.gz,
   mac-x64.tar.gz and win-x64.zip; exact versions in python-packages.lock.txt.
 - Archives because exFAT keeps neither symlinks nor the executable flag.
 - First run unpacks to ~/.dashboard_suite_runtime (Mac) or
   %LOCALAPPDATA%\DashboardSuite (Windows). A .ok marker written last means a
   half-finished unpack is redone. Older versions are removed.
 - The chip is read from hardware, so Rosetta cannot mislead it. Quarantine
   flag cleared. Bytecode caches go to the home folder, not the stick.
 - Fallback order: bundled, then an installed Python 3.9+ with a private venv
   at ~/.dashboard_suite_venv (rebuilt if broken), then per-user pip. The
   /usr/bin/python3 stub is only tried when Command Line Tools exist.
 - Mac: Apple Silicon and Intel, macOS 11+. Windows: 64-bit 10 (1803+) and 11.


====================================================================
 PART 8  READING IT ALL AS TEXT
====================================================================

 8.1 Summaries
 Dashboard      Live                       File (works offline)
 Stocks         8766/api/summary           stocks_dashboard/cache/summary.txt
 Truth Social   8765/summary               truth_social_filter/cache/summary.txt
 Company news   8194/api/summary           company_positive_negative_5_day_news/summary.txt
 China/Russia   none                       china_russia_middleeast_summary.txt
 God's Eye      none                       gods_eye_summary.txt

 Stocks summary sections, in order: coverage, market mood (Fear & Greed, VIX,
 Fed, BoE), oversold, overbought (RSI above 70), 33%+ below high, within 2% of
 high, uptrend daily/weekly/monthly (alerted stocks only), H&S top, inverse H&S,
 volatility spike, liquidity, news, WEF. Up to 12 tickers a list. Quotes over
 30 min are marked STALE. Built from memory, so it never triggers a fetch.
 Summary thresholds are the page defaults, not the sliders.

 8.2 SKILL.md
 Tells an agent (offlineclaw, OpenClaw) what the dashboards are, how to start,
 refresh and read them, and the honesty rules for briefing.

 8.3 plugin.js (offlineclaw plugin "dashboards")
 Tools: brief, status, start (headless), refresh, stop.
 brief: live server when allowed, else the saved file, and says which. compact
 keeps headline lines only (about 2,000 characters for all five). It never
 composes a figure of its own.


====================================================================
 PART 9  TESTS AND DEVELOPER SCRIPTS
====================================================================

 tools/test_summaries.py  No network, no packages. Company lists match, stocks empty and populated,
                          HH&HL port, H&S lines; Truth classify parity with the
                          JS; God's Eye with a missing block; company selftest;
                          refresh loop keeps going after a failure; China page
                          scripts parse.
 check_fallbacks.py       Every listed ticker has 2+ independent sources.
                          --live N also fetches N through FT and Nasdaq.
 debug_tickers.py         Tests every ticker and reports failures.
 debug.py                 System and package information.
 test_data.py             Quick check that price fetching works.
 central_banks.py         Run directly for JSON; --offline uses cache/built-in.
 wef_events.py            Run directly for JSON; --force skips the cache.
 liquidity.py             Run directly to print all four gauges.


====================================================================
 PART 10  MISMATCHES AND UNUSED CODE FOUND WHILE WRITING THIS
====================================================================

 Counts that do not match
 - None currently known.

 Wording that does not match the behaviour
 - stock_fetch.py docstring says yfinance tries 1y first. The code starts at 5y.
 - SKILL.md says "volume spikes". It is a volatility test on prices; no volume is
   fetched.
 - plugin.js compact mode looks for "VOLUME", but the summary line says "VOLATILITY
   SPIKE", so that line is dropped from compact briefs.
 - Fear & Greed note says "Alerts when <40 or <25". It only changes colours; no alert
   count or notification uses it.
 - The VIX chart was removed from the stocks page, but /api/volx stays; VIX now
   appears only in the text summary.
 - rss_server.py docstring leaves out /summary and /refresh.
 - check_private.py docstring says to update app.py. The list lives in watchlist.py.

 Code present but not used
 - dashboard.html: calcRSI() and calcVolSpike() are never called (the server computes
   both). The 'alerts' filter branch in renderList() has no tab.
 - company news: short-themes.mjs is never imported, and the theme column in
   companies.mjs is ignored by server.mjs, so no theme is shown.
 - God's Eye: country-connections-data is an empty list, so loadConnections() draws
   nothing and its "connections" chip reads 0.

 Behaviour worth knowing
 - The stocks text summary uses page defaults (RSI 30, dip 33%), not the sliders.
 - H&S status can change before the week ends, since the current week counts at its
   latest close.
 - Exchange open/shut ignores public holidays.
 - Shipping routes and rail termini are approximations and labelled as such.
 - Rail links are drawn straight between stations, not along the exact track.
 - Generic word lists drive sentiment on Truth Social and company news; they read
   words, not meaning.


====================================================================
 PART 11  RUNNING IT: USB, ANDROID AND TROUBLESHOOTING
====================================================================

 USB stick
 - Format exFAT so Mac and Windows both read and write it. The folder is about
   260 MB. Copy the WHOLE folder; it can live anywhere under any name.
 - exFAT drops the executable flag, so a .command may refuse to double-click. Drag
   START (Mac).command into a Terminal window and press Enter, or run chmod +x on it.
 - Gatekeeper warning on Mac: right-click the file, Open, Open.
 - To leave no trace on a borrowed computer, delete ~/.dashboard_suite_runtime (Mac)
   or %LOCALAPPDATA%\DashboardSuite (Windows). The next START unpacks it again.

 First run
 About 20 s on a Mac, about a minute on Windows, then immediate. Needs no internet.
 Antivirus or SmartScreen may slow the first Windows run; let it finish.

 Android
 Copy the folder over, open gods_eye_dashboard.html from the Files app in Chrome or
 Firefox (Firefox is most reliable for local files). The saved China/Russia HTML opens
 the same way. The other windows are Mac and Windows only. Optional: in Termux run
 pkg install python, then python truth_social_filter/rss_server.py, to make
 military flights and buoys live.

 Troubleshooting
 "Python 3 not found"        Runtime unusable and no Python installed. Check the runtime
                             folder has its 3 archives and about 1 GB of disk is free.
 "Could not unpack runtime"  Disk full or incomplete copy. Copy the folder again.
 "Could not install          The launcher prints the exact pip command. Run it, then
 dependencies"               START again.
 Window flashes and closes   Run the .bat by name from Command Prompt to see the error.
 Dashboard opens empty       A server did not start. Find its log (dashboard_suite_*.log
                             in the temp folder) and check ports 8766, 8765 and 8194.
 Stocks show "..." for ages  Normal: one ticker at a time, a few minutes in all.
 Truth Social "Saved copy"   Neither source reachable; last saved feed is shown.
 Port already in use         START stops only its own old servers and reports anything
                             else on the port. Quit that program or reboot.
 News "No matching           Normal. Panels show only real headlines, or the last real
 headlines"                  batch with its date.
 'curl' not recognized       Very old Windows. The wait is skipped; give servers a moment.
